~ chicken-core (chicken-5) /manual/Module srfi-4
Trap1[[tags: manual]]2[[toc:]]34== Module srfi-456Homogeneous numeric vector datatypes. Also see the7[[http://srfi.schemers.org/srfi-4/srfi-4.html|original SRFI-4 document]].89When loaded, the feature identifier {{srfi-4}} is defined.1011=== CHICKEN implementation specifics and extensions1213* Procedures for [[Module (chicken blob)|blob]] conversion, subvectors and vector I/O are provided.14* SRFI-17 setters for {{XXXvector-ref}} are defined.15* Constructors allow allocating the storage in non garbage collected memory.1617=== Blob conversions1819As a SRFI-4 vector is basically just a [[Module (chicken blob)|blob]]20wrapped by a SRFI-4 type "header object" to structure its contents,21there are several procedures which can convert between blobs and22SRFI-4 vectors.2324<procedure>(u8vector->blob U8VECTOR)</procedure><br>25<procedure>(s8vector->blob S8VECTOR)</procedure><br>26<procedure>(u16vector->blob U16VECTOR)</procedure><br>27<procedure>(s16vector->blob S16VECTOR)</procedure><br>28<procedure>(u32vector->blob U32VECTOR)</procedure><br>29<procedure>(s32vector->blob S32VECTOR)</procedure><br>30<procedure>(u64vector->blob U64VECTOR)</procedure><br>31<procedure>(s64vector->blob S64VECTOR)</procedure><br>32<procedure>(f32vector->blob F32VECTOR)</procedure><br>33<procedure>(f64vector->blob F64VECTOR)</procedure><br>34<procedure>(u8vector->blob/shared U8VECTOR)</procedure><br>35<procedure>(s8vector->blob/shared S8VECTOR)</procedure><br>36<procedure>(u16vector->blob/shared U16VECTOR)</procedure><br>37<procedure>(s16vector->blob/shared S16VECTOR)</procedure><br>38<procedure>(u32vector->blob/shared U32VECTOR)</procedure><br>39<procedure>(s32vector->blob/shared S32VECTOR)</procedure><br>40<procedure>(u64vector->blob/shared U64VECTOR)</procedure><br>41<procedure>(s64vector->blob/shared S64VECTOR)</procedure><br>42<procedure>(f32vector->blob/shared F32VECTOR)</procedure><br>43<procedure>(f64vector->blob/shared F64VECTOR)</procedure><br>4445Each of these procedures return the contents of the given vector as a46'packed' blob. The byte order in that vector is platform-dependent47(for example little-endian on an '''Intel''' processor). The48{{/shared}} variants return a blob that shares memory with the49contents of the vector, the others will copy the contents of the50SRFI-4 vector's internal blob object.5152<procedure>(blob->u8vector BLOB)</procedure><br>53<procedure>(blob->s8vector BLOB)</procedure><br>54<procedure>(blob->u16vector BLOB)</procedure><br>55<procedure>(blob->s16vector BLOB)</procedure><br>56<procedure>(blob->u32vector BLOB)</procedure><br>57<procedure>(blob->s32vector BLOB)</procedure><br>58<procedure>(blob->u64vector BLOB)</procedure><br>59<procedure>(blob->s64vector BLOB)</procedure><br>60<procedure>(blob->f32vector BLOB)</procedure><br>61<procedure>(blob->f64vector BLOB)</procedure><br>62<procedure>(blob->u8vector/shared BLOB)</procedure><br>63<procedure>(blob->s8vector/shared BLOB)</procedure><br>64<procedure>(blob->u16vector/shared BLOB)</procedure><br>65<procedure>(blob->s16vector/shared BLOB)</procedure><br>66<procedure>(blob->u32vector/shared BLOB)</procedure><br>67<procedure>(blob->s32vector/shared BLOB)</procedure><br>68<procedure>(blob->u64vector/shared BLOB)</procedure><br>69<procedure>(blob->s64vector/shared BLOB)</procedure><br>70<procedure>(blob->f32vector/shared BLOB)</procedure><br>71<procedure>(blob->f64vector/shared BLOB)</procedure><br>7273Each of these procedures return a vector where the argument {{BLOB}}74is taken as a 'packed' representation of the contents of the75vector. The {{/shared}} variants return a vector that shares memory76with the contents of the blob, the others will copy the blob.7778=== Subvectors7980<procedure>(subu8vector U8VECTOR FROM TO)</procedure><br>81<procedure>(subu16vector U16VECTOR FROM TO)</procedure><br>82<procedure>(subu32vector U32VECTOR FROM TO)</procedure><br>83<procedure>(subu64vector U32VECTOR FROM TO)</procedure><br>84<procedure>(subs8vector S8VECTOR FROM TO)</procedure><br>85<procedure>(subs16vector S16VECTOR FROM TO)</procedure><br>86<procedure>(subs32vector S32VECTOR FROM TO)</procedure><br>87<procedure>(subs64vector S32VECTOR FROM TO)</procedure><br>88<procedure>(subf32vector F32VECTOR FROM TO)</procedure><br>89<procedure>(subf64vector F64VECTOR FROM TO)</procedure><br>9091Creates a fresh number vector of the same type as the argument vector92with the elements at the positions {{FROM}} up to but not including93{{TO}}.9495=== Vector I/O9697<procedure>(read-u8vector [LENGTH [PORT]])</procedure>9899Reads {{LENGTH}} bytes from the {{PORT}} and returns a fresh100{{u8vector}}, or as many as are available before end-of-file is101encountered. {{PORT}} defaults to the value of {{(current-input-port)}}.102If no bytes are available before the end-of-file, {{#!eof}} is returned.103104If {{LENGTH}} is {{#f}}, the vector will be filled completely until105end-of-file is reached.106107<procedure>(read-u8vector! LENGTH U8VECTOR [PORT [START]])</procedure>108109Reads {{LENGTH}} bytes from the {{PORT}} writing the read input into110{{U8VECTOR}} beginning at {{START}} (or 0 if not given). {{PORT}} defaults111to the value of {{(current-input-port)}}.112113If {{LENGTH}} is {{#f}}, the vector will be filled completely until end-of-file is reached.114This procedure returns the number of bytes read.115116<procedure>(write-u8vector U8VECTOR [PORT [START [END]]])</procedure>117118Writes the bytes {{U8VECTOR}} between the indices {{START}} (inclusive) and {{END}} (exclusive) to {{PORT}}.119120{{PORT}} defaults to the value of {{(current-output-port)}}.121122== SRFI-4 specification123124SRFI-4 describes a set of datatypes for vectors whose elements are125of the same numeric type (signed or unsigned exact integer or inexact126real of a given precision). These datatypes support operations analogous127to the Scheme vector type, but they are distinct datatypes. An external128representation is specified which must be supported by the {{read}} and129{{write}} procedures and by the program parser (i.e. programs can contain130references to literal homogeneous vectors).131132=== Datatypes133134There are 8 datatypes of exact integer homogeneous vectors (which will be135called integer vectors):136137<table>138<tr><th>Datatype</th><th>Type of elements</th></tr>139<tr><td>{{s8vector}}</td><td>signed exact integer in the range -(2^7) to (2^7)-1</td></tr>140<tr><td>{{u8vector}}</td><td>unsigned exact integer in the range 0 to (2^8)-1</td></tr>141<tr><td>{{s16vector}}</td><td>signed exact integer in the range -(2^15) to (2^15)-1</td></tr>142<tr><td>{{u16vector}}</td><td>unsigned exact integer in the range 0 to (2^16)-1</td></tr>143<tr><td>{{s32vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr>144<tr><td>{{u32vector}}</td><td>unsigned exact integer in the range 0 to (2^32)-1</td></tr>145<tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr>146<tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr>147<tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^63) to (2^63)-1</td></tr>148<tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr></table>149150There are 2 datatypes of inexact real homogeneous vectors (which will be151called float vectors):152153<table>154<tr><th>Datatype</th><th>Type of elements</th></tr>155<tr><td>{{f32vector}}</td><td>inexact real</td></tr>156<tr><td>{{f64vector}}</td><td>inexact real</td></tr></table>157158The only difference between the two float vector types is that159{{f64vector}}s preserve at least as much precision as {{f32vector}}s.160161Each homogeneous vector datatype has an external representation which162is supported by the {{read}} and {{write}} procedures and by the program163parser. Each datatype also has a set of associated predefined procedures164analogous to those available for Scheme's heterogeneous vectors.165166=== External representation167168<read>#u8</read><br>169<read>#u16</read><br>170<read>#u32</read><br>171<read>#s8</read><br>172<read>#s16</read><br>173<read>#s32</read><br>174<read>#f32</read><br>175<read>#f64</read><br>176177The external representation of instances of the datatype {{XXXvector}}178is {{#XXX( ...elements... )}}.179180For example,181182 #u8(0 #e1e2 #xff) ; a u8vector of length 3 containing 0, 100, 255183 #f64(-1.5) ; a f64vector of length 1 containing -1.5.184185This external representation is also available in program source code. For example,186187 (set! x '#u8(1 2 3))188189will set {{x}} to the object {{#u8(1 2 3)}}. Since CHICKEN 4.9.0, literal homogeneous vectors do not have to be quoted. Homogeneous vectors can appear in quasiquotations but must not contain {{unquote}} or {{unquote-splicing}} forms. ''I.e.'',190191 `(,x #u8(1 2)) ; legal192 `#u8(1 ,x 2) ; illegal193194Elements may also be characters or strings, in that case they are interpreted195as a sequence of numerical character codes. For example,196197 '#u8(#\x7f "EL" #\F 2 1)198199is equivalent to200201 '#u8(#\x7f #\x45 #\x4c #\x46 2 1)202203Character literals inside numeric vectors expand into the UTF-8 sequence of204the characters they represent, for strings the contained characters205are interpreted in whatever encoding is used for the text file or stream206in which the literal appears.207208Note that {{#u8"..."}} can be used as an abbreviation for the special case209{{#u8("...")}}.210211=== Predicates212213<procedure>(u8vector? OBJ)</procedure><br>214<procedure>(s8vector? OBJ)</procedure><br>215<procedure>(u16vector? OBJ)</procedure><br>216<procedure>(s16vector? OBJ)</procedure><br>217<procedure>(u32vector? OBJ)</procedure><br>218<procedure>(s32vector? OBJ)</procedure><br>219<procedure>(u64vector? OBJ)</procedure><br>220<procedure>(s64vector? OBJ)</procedure><br>221<procedure>(f32vector? OBJ)</procedure><br>222<procedure>(f64vector? OBJ)</procedure><br>223224Return {{#t}} if {{obj}} is an object of the specified type or {{#f}} if not.225226<procedure>(number-vector? OBJ)</procedure>227228Return {{#t}} if {{obj}} is a number vector, {{#f}} if not. A "number vector" is any of the homogeneous number vector types defined by SRFI-4, ie it's one of {{u8vector}}, {{s8vector}}, {{u16vector}}, {{s16vector}}, {{u32vector}}, {{s32vector}}, {{u64vector}}, {{s64vector}}, {{f32vector}} or {{f64vector}}).229230231=== Constructors232233<procedure>(make-u8vector N [U8VALUE NONGC FINALIZE])</procedure><br>234<procedure>(make-s8vector N [S8VALUE NONGC FINALIZE])</procedure><br>235<procedure>(make-u16vector N [U16VALUE NONGC FINALIZE])</procedure><br>236<procedure>(make-s16vector N [S16VALUE NONGC FINALIZE])</procedure><br>237<procedure>(make-u32vector N [U32VALUE NONGC FINALIZE])</procedure><br>238<procedure>(make-s32vector N [S32VALUE NONGC FINALIZE])</procedure><br>239<procedure>(make-u64vector N [U64VALUE NONGC FINALIZE])</procedure><br>240<procedure>(make-s64vector N [S64VALUE NONGC FINALIZE])</procedure><br>241<procedure>(make-f32vector N [F32VALUE NONGC FINALIZE])</procedure><br>242<procedure>(make-f64vector N [F64VALUE NONGC FINALIZE])</procedure><br>243244Return a newly-allocated SRFI-4 homogeneous number vector of length N.245246If the optional fill VALUE is specified, it specifies the initial247value for each slot in the vector. If not, the content of the vector248is unspecified as the underlying memory is uninitialized.249Particularly this means that entries in {{f32vector}} or {{f64vector}}250may be i.e. a NaN-value.251252The type of the fill value must be compatible with the elements of the253vector datatype. It is an error if otherwise -- for example, if an254inexact integer is passed to {{make-u8vector}}.255256On CHICKEN, these procedures have been extended to allow allocating257the storage in non-garbage collected memory, as follows:258259The optional arguments {{NONGC}} and {{FINALIZE}} define whether the260vector should be allocated in a memory area not subject to garbage261collection and whether the associated storage should be automatically262freed (using finalization) when there are no references from Scheme263variables and data. {{NONGC}} defaults to {{#f}} (the vector will be264located in normal garbage collected memory) and {{FINALIZE}} defaults265to {{#t}}. Note that the {{FINALIZE}} argument is only used when266{{NONGC}} is true.267268<procedure>(u8vector U8VALUE ...)</procedure><br>269<procedure>(s8vector S8VALUE ...)</procedure><br>270<procedure>(u16vector U16VALUE ...)</procedure><br>271<procedure>(s16vector S16VALUE ...)</procedure><br>272<procedure>(u32vector U32VALUE ...)</procedure><br>273<procedure>(s32vector S32VALUE ...)</procedure><br>274<procedure>(u64vector U64VALUE ...)</procedure><br>275<procedure>(s64vector S64VALUE ...)</procedure><br>276<procedure>(f32vector F32VALUE ...)</procedure><br>277<procedure>(f64vector F64VALUE ...)</procedure><br>278279Return a newly-allocated SRFI-4 homogeneous number vector of the specified280type, composed of the arguments.281282=== Length283284<procedure>(u8vector-length U8VECTOR)</procedure><br>285<procedure>(s8vector-length S8VECTOR)</procedure><br>286<procedure>(u16vector-length U16VECTOR)</procedure><br>287<procedure>(s16vector-length S16VECTOR)</procedure><br>288<procedure>(u32vector-length U32VECTOR)</procedure><br>289<procedure>(s32vector-length S32VECTOR)</procedure><br>290<procedure>(u64vector-length U64VECTOR)</procedure><br>291<procedure>(s64vector-length S64VECTOR)</procedure><br>292<procedure>(f32vector-length F32VECTOR)</procedure><br>293<procedure>(f64vector-length F64VECTOR)</procedure><br>294295Returns the length of the SRFI-4 homogeneous number VECTOR.296297=== Getters298299<procedure>(u8vector-ref U8VECTOR I)</procedure><br>300<procedure>(s8vector-ref S8VECTOR i)</procedure><br>301<procedure>(u16vector-ref U16VECTOR I)</procedure><br>302<procedure>(s16vector-ref S16VECTOR I)</procedure><br>303<procedure>(u32vector-ref U32VECTOR I)</procedure><br>304<procedure>(s32vector-ref S32VECTOR I)</procedure><br>305<procedure>(u64vector-ref U64VECTOR I)</procedure><br>306<procedure>(s64vector-ref S64VECTOR I)</procedure><br>307<procedure>(f32vector-ref F32VECTOR I)</procedure><br>308<procedure>(f64vector-ref F64VECTOR I)</procedure><br>309310Return the value of the ''i''th element of the SRFI-4 homogeneous311number vector, where {{I}} is a nonnegative exact integer less312than the length of the vector.313314=== Setters315316<procedure>(u8vector-set! U8VECTOR I U8VALUE)</procedure><br>317<procedure>(s8vector-set! S8VECTOR I S8VALUE)</procedure><br>318<procedure>(u16vector-set! U16VECTOR I U16VALUE)</procedure><br>319<procedure>(s16vector-set! S16VECTOR I S16VALUE)</procedure><br>320<procedure>(u32vector-set! U32VECTOR I U32VALUE)</procedure><br>321<procedure>(s32vector-set! S32VECTOR I S32VALUE)</procedure><br>322<procedure>(u64vector-set! U64VECTOR I U64VALUE)</procedure><br>323<procedure>(s64vector-set! S64VECTOR I S64VALUE)</procedure><br>324<procedure>(f32vector-set! F32VECTOR I F32VALUE)</procedure><br>325<procedure>(f64vector-set! F64VECTOR I F64VALUE)</procedure><br>326327Set the {{i}}th element of the SRFI-4 homogeneous number VECTOR to328VALUE. {{I}} is a nonnegative exact integer less than the length of329the vector and VALUE must be the same type as the elements of the330vector datatype.331332Additionally, SRFI-17 setters are defined on all {{xxxvector-ref}}333procedures. For example, to set the {{i}}th element of SRFI-4334{{u8vector}} to {{u8value}}:335336 (set! (u8vector-ref u8vector i) u8value)337338=== Conversions339340<procedure>(u8vector->list U8VECTOR)</procedure><br>341<procedure>(s8vector->list S8VECTOR)</procedure><br>342<procedure>(u16vector->list U16VECTOR)</procedure><br>343<procedure>(s16vector->list S16VECTOR)</procedure><br>344<procedure>(u32vector->list U32VECTOR)</procedure><br>345<procedure>(s32vector->list S32VECTOR)</procedure><br>346<procedure>(u64vector->list U64VECTOR)</procedure><br>347<procedure>(s64vector->list S64VECTOR)</procedure><br>348<procedure>(f32vector->list F32VECTOR)</procedure><br>349<procedure>(f64vector->list F64VECTOR)</procedure><br>350351Return a list consisting of the elements of SRFI-4 homogeneous number352VECTOR.353354<procedure>(list->u8vector U8LIST)</procedure><br>355<procedure>(list->s8vector S8LIST)</procedure><br>356<procedure>(list->u16vector U16LIST)</procedure><br>357<procedure>(list->s16vector S16LIST)</procedure><br>358<procedure>(list->u32vector U32LIST)</procedure><br>359<procedure>(list->s32vector S32LIST)</procedure><br>360<procedure>(list->u64vector U64LIST)</procedure><br>361<procedure>(list->s64vector S64LIST)</procedure><br>362<procedure>(list->f32vector F32LIST)</procedure><br>363<procedure>(list->f64vector F64LIST)</procedure><br>364365Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting366of the elements of LIST. Each element of LIST must be compatible367with the datatype of VECTOR.368369=== Release number vectors allocated in static memory370371<procedure>(release-number-vector NVECTOR)</procedure>372373Release the storage of a SRFI-4 vector that was allocated in374non-garbage collected memory (for example using the {{NONGC}} argument375for one of the {{make-XXXvector}} constructor procedures). The effect376of calling this procedure with a number vector allocated in normal377garbage collected memory is undefined.378379380---381Previous: [[Module r4rs]]382383Next: [[Module (chicken base)]]